﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>文件对象 - 方法 &amp; 属性 | AutoHotkey v2</title>
<meta name="description" content="The file 对象 provides an interface 遍历 a file to perform actions, such as reading or writing data, or to retrieve or set values, such as 长度." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>文件对象</h1>

<p>提供文件输入/输出的接口. <a href="../commands/FileOpen.htm">打开文件</a> 返回此类型的对象.</p>

<h2 id="Members">对象成员</h2>
<p>属性:</p>
<ul>
  <li><a href="#Pos">位置</a>: 检索或设置文件指针的位置.</li>
  <li><a href="#Length">长度</a>: 检索或设置文件的大小.</li>
  <li><a href="#AtEOF">在末尾</a>: 检索一个非零值, 如果文件指针已到达文件末尾.</li>
  <li><a href="#Encoding">编码</a>: 检索或设置此文件对象使用的文本编码.</li>
  <li><a href="#Handle">句柄</a>: 检索旨在与 动态库调用 一起使用的系统文件句柄.</li>
</ul>
<p>方法:</p>
<ul>
  <li><a href="#Read">读</a>: 从文件中读取字符串, 并向前移动文件指针(向右).</li>
  <li><a href="#Write">写</a>: 写入字符串到文件并向前移动文件指针.</li>
  <li><a href="#ReadLine">读行</a>: 从文件中读取一行文本并向前移动文件指针.</li>
  <li><a href="#WriteLine">写行</a>: 根据打开文件时使用的标志, 写入后面跟着 <code>`n</code> 或 <code>`r`n</code> 的字符串. 向前移动文件指针.</li>
  <li><a href="#ReadNum">读<em>NumType</em></a>: 从文件中读取指定类型的数据并向前移动文件指针.</li>
  <li><a href="#WriteNum">写<em>NumType</em></a>: 写入指定类型的数据到文件并向前移动文件指针.</li>
  <li><a href="#RawRead">读源码</a>: 从文件读取原始的二进制数据到内存并向前移动文件指针.</li>
  <li><a href="#RawWrite">写源码</a>: 写入原始的二进制数据到文件并向前移动文件指针.</li>
  <li><a href="#Seek">移动指针</a>: 移动文件指针. 如果第二个参数被省略, 等同于 <code>文件.位置 := Distance</code>.</li>
  <li><a href="#Close">关闭</a>: 关闭文件, 将缓存中的所有数据写入磁盘并释放共享锁定.</li>
</ul>

<div class="methodShort" id="Read"><h2>读</h2>
<p>从文件读取字符串并向前移动文件指针.</p>
<pre class="Syntax">字符串 := 文件.<span class="func">读</span>(<span class="optional">Characters</span>)</pre>
<dl>
  <dt>Characters</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>需读取的最大字符数. 如果省略, 则读取文件的剩余部分并作为单个字符串返回. 如果 File 对象创建于非搜寻设备(例如控制台缓冲区或管道) 的句柄, 省略此参数可能引起执行方法失败或仅返回当前可用的数据.</p>
  </dd>
</dl>
<p><strong>返回</strong> 字符串.</p>
</div>

<div class="methodShort" id="Write"><h2>写</h2>
<p>写入字符串到文件并向前移动文件指针.</p>
<pre class="Syntax">文件.<span class="func">写</span>(字符串)</pre>
<dl>
  <dt>字符串</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>要写入的字符串.</p>
  </dd>
</dl>
<p><strong>返回</strong> 写入的字节数(不是字符数).</p>
</div>

<div class="methodShort" id="ReadLine"><h2>读行</h2>
<p>从文件中读取一行文本并使文件指针向前移动.</p>
<pre class="Syntax">TextLine := 文件.<span class="func">读行</span>()</pre>
<p><strong>返回</strong> 一行文本, 不包括行结束符.</p>
<p>可以读取长达 65,534 个字符的行. 如果一个行的长度超过这个长度, 则该行的其余部分将通过对此方法的后续调用返回.</p></div>

<div class="methodShort" id="WriteLine"><h2>写行</h2>
<p>根据打开文件时使用的标志, 写入后面跟着 <code>`n</code> 或 <code>`r`n</code> 的字符串. 向前移动文件指针.</p>
<pre class="Syntax">文件.<span class="func">写行</span>(<span class="optional">字符串</span>)</pre>
<dl>
  <dt>字符串</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>可选的字符串.</p>
  </dd>
</dl>
<p><strong>返回</strong> 写入的字节数(不是字符数).</p>
</div>

<div class="methodShort" id="ReadNum"><h2>读<i>NumType</i></h2>
<p>从文件中读取指定类型的数据并使文件指针向前移动.</p>
<pre class="Syntax">Num := 文件.读<i>NumType</i>()</pre>
<p><em>NumType</em> 可以是 无符号整数, 整数, 64位整数, 短整数, 无符号短整数, 字符, 无符号字符, 双精度小数 或 浮点数. 这些类型名称的含义与 <a href="../commands/DllCall.htm#types">动态库调用</a> 中的相同.</p>
<p><strong>返回</strong> 一个数字, 如果读取成功, 否则为空字符串. 如果读出的字节数为非零, 但小于 <em>NumType</em> 的大小, 那么缺失的字节数被假定为零.</p>
</div>

<div class="methodShort" id="WriteNum"><h2>写<i>NumType</i></h2>
<p>写入指定类型的数据到文件并使文件指针向前移动.</p>
<pre class="Syntax">文件.写<i>NumType</i>(Num)</pre>
<dl>
  <dt>Num</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a>或<a href="../Concepts.htm#numbers">浮点数</a></p>
    <p>写入的数字.</p>
  </dd>
</dl>
<p><em>NumType</em> 可以是 无符号整数, 整数, 64位整数, 短整数, 无符号短整数, 字符, 无符号字符, 双精度小数 或 浮点数. 这些类型名称的含义与 <a href="../commands/DllCall.htm#types">动态库调用</a> 中的相同.</p>
<p><strong>返回</strong> 写入的字节数. 例如, 如果成功, WriteUInt 返回 4.</p>
</div>

<div class="methodShort" id="RawRead"><h2>读源码</h2>
<p>从文件读取原始的二进制数据到内存并向前移动文件指针.</p>
<pre class="Syntax">文件.<span class="func">读源码</span>(Buffer <span class="optional">, Bytes</span>)</pre>
<dl>
  <dt>Buffer</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#objects">对象</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>将接收数据的类<a href="Buffer.htm">缓冲</a>对象或内存地址.</p>
    <p>建议读入 <a href="../commands/BufferAlloc.htm">创建缓冲区</a> 创建的<a href="Buffer.htm">缓冲</a>. 如果省略 <em>Bytes</em>, 它默认为缓冲的大小. 如果 <em>Bytes</em> 超过缓冲的大小, 则抛出异常.</p>
    <p>如果传递一个内存地址, 则 <em>Bytes</em> 也必须指定.</p>
  </dd>
  <dt>Bytes</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要读取的最大字节数. 这是可选的, 当 <em>Buffer</em> 是一个对象或字符串变量(不推荐); 否则, 它是必需的.</p>
  </dd>
</dl>
<p><strong>返回</strong> 读取的字节数.</p>
</div>

<div class="methodShort" id="RawWrite"><h2>写源码</h2>
<p>写入原始的二进制数据到文件并向前移动文件指针.</p>
<pre class="Syntax">文件.<span class="func">写源码</span>(Data <span class="optional">, Bytes</span>)</pre>
<dl>
  <dt>Data</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#objects">对象</a>, <a href="../Concepts.htm#strings">字符串</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>类<a href="Buffer.htm">缓冲</a>对象或包含二进制数据的字符串, 或内存地址. 如果指定了一个对象或字符串, <em>Bytes</em> 是可选的, 默认为缓冲或字符串的大小. 否则, 必须指定 <em>Bytes</em>.</p>
  </dd>
  <dt>Bytes</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要写入的字节数. 当 <em>Data</em> 是一个对象或字符串时, 这是可选的; 否则, 它是必需的.</p>
  </dd>
</dl>
<p><strong>返回</strong> 写入的字节数.</p>
</div>

<div class="methodShort" id="Seek"><h2>移动指针</h2>
<p>移动文件指针.</p>
<pre class="Syntax">文件.<span class="func">移动指针</span>(Distance <span class="optional">, Origin := 0</span>)
</pre>
<dl>
  <dt>Distance</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要移动的距离, 单位为字节. 较小的值更接近文件的开始处.</p>
  </dd>
  <dt>Origin</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>文件指针开始移动的起点. 必须为下列值的其中一个:</p>
    <ul>
      <li>0(SEEK_SET): 文件的开始处. <i>Distance</i> 必须为零或更大.</li>
      <li>1(SEEK_CUR): 文件指针的当前位置.</li>
      <li>2(SEEK_END): 文件的末尾. <i>Distance</i> 通常应该为负数.</li>
    </ul>
    <p>如果省略, 当 Distance 为负数时, <i>Origin</i> 默认为 SEEK_END, 而其他情况时为 SEEK_SET.</p></dd>
</dl>
<p><strong>返回</strong> 非零值, 如果成功, 否则为 0.</p>
</div>

<div class="methodShort" id="Pos"><h2>位置</h2>
<p>检索或设置文件指针的当前位置.</p>
<pre class="Syntax">位置 := 文件.位置</pre>
<pre class="Syntax">文件.位置 := NewPos</pre>
<p>等同于 <code>文件.移动指针(NewPos)</code>.</p>
<p>位置是从文件开始的字节偏移, 其中 0 是第一个字节. 当数据被写入或从文件中读取时, 文件指针会自动移动到该数据之后的下一个字节.</p>
</div>

<div class="methodShort" id="Length"><h2>长度</h2>
<p>获取或设置文件的大小.</p>
<pre class="Syntax">FileSize := 文件.长度</pre>
<pre class="Syntax">文件.长度 := NewSize</pre>
<p><em>FileSize</em> 和 <em>NewSize</em> 是文件的大小, 单位为字节.</p>
<p>此属性应该仅用于真实的文件. 如果 File 对象创建于管道的句柄, 那么它可能返回管道内部缓冲区中当前可用的数据量, 但不能保证一定如此.</p></div>

<div class="methodShort" id="AtEOF"><h2>在末尾</h2>
  <p>当文件指针到达文件末尾时, 返回非零值, 否则为零.</p>
<pre class="Syntax">IsAtEOF := 文件.在末尾</pre>
  <p>此属性应该仅用于真实的文件. 如果 File 对象创建于非寻址设备(例如控制台缓冲区或管道) 的句柄, 那么返回的值可能没有意义, 因为这些设备逻辑上没有"文件末尾".</p></div>

<div class="methodShort" id="Close"><h2>关闭</h2>
<p>关闭文件, 将缓存中的任何数据写入磁盘, 并释放共享锁.</p>
<pre class="Syntax">文件.<span class="func">关闭</span>()</pre>
<p>虽然在释放对象时文件会自动关闭, 但建议尽快关闭文件.</p></div>

<div class="methodShort" id="Encoding"><h2>编码</h2>
<p>检索或设置此文件对象使用的文本编码.</p>
<pre class="Syntax">RetrievedEncoding := 文件.编码</pre>
<pre class="Syntax">文件.编码 := NewEncoding</pre>
  <p><em>RetrievedEncoding</em> 和 <em>NewEncoding</em> 是一个数字代码页标识符(请参阅 <a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">MSDN</a>) 或以下字符串之一:</p>
  <ul>
	<li><code>UTF-8</code>: Unicode UTF-8, 相当于 CP65001.</li>
	<li><code>UTF-16</code>: Unicode UTF-16 小端字节顺序标识, 相当于 CP1200.</li>
	<li><code>CP<i>nnn</i></code>: 带有数字标识符 <i>nnn</i> 的编码页.</li>
  </ul>
  <p><em>RetrievedEncoding</em> 不会返回带 <code>-RAW</code> 后缀的值, 不论文件如何被打开或是否包含字节顺序标识(BOM). 设置 <em>NewEncoding</em> 不会增加或移除 BOM, 因为 BOM 通常在文件建立时就被写入其中了.</p>
  <p>设置 <em>NewEncoding</em> 为 <code>UTF-8-RAW</code> 或 <code>UTF-16-RAW</code> 合法, 但 <code>-RAW</code> 后缀将被忽略. 这仅适用于 <code>文件.编码</code>, 而不会影响 <a href="../commands/FileOpen.htm">打开文件</a>.</p>
</div>

<div class="methodShort" id="Handle"><h2>句柄</h2>
  <p>返回用于 动态库调用 的系统文件句柄. 请参阅 <a href="http://msdn.microsoft.com/en-us/library/aa363858.aspx">CreateFile</a>.</p>
<pre class="Syntax">文件.句柄</pre>
<p>文件对象使用内部缓冲区读取或写入. 如果数据已经被写入对象的内部缓冲区, 则在返回句柄前会确保把数据写入磁盘. 如果缓冲区中包含从文件读取的数据, 则会把数据丢弃且文件指针的实际位置被重设为由 <code>文件.位置</code> 表示的逻辑位置.</p></div>

</body>
</html>